Basic stuff

If you don't know much about how to use CGI scripts in your web page, here is a very brief introduction. There are many great sites on the internet for tutorials.

Let' s assume you want to create a web site with some forms. Do the following

1) Create a html document in filepath "c:\Apache\htdocs\test.html" with this:

<form action="cgi-bin/test.cgi" method="GET">

Enter some text here:

<input type="text" name="text" size=30>

<input type="submit"><p></form>

This creates an input on your page for the user to enter text. Most Web-Editors allow you to create stuff like this automatically. Notice the GET method used here. When the user presses "Submit", the browser will call the URL:

http://127.0.0.1/cgi-bin/test.cgi?text=what_you_typed

2) Now create test.cgi in the directory C:\Apache\cgi-bin. Load Apache. Enter the following Perl Script:

#!C:\Perl\bin\perl.exe

print "Content-Type: text/html\n\n";

print "$ENV{'QUERY_STRING'}<br>";

Save changes. You can test now this script in two ways:

•	Edit the Query string with something and press F9. This calls the cgi script directly, without the html being used.

•	Select Open URL, and select "http://127.0.0.1/test.html". This opens the html, and you can press the button and test etc. In this manner you can use also the POST method.

·	·	·	·	·

 You should see the result in a dynamically created html page on the right. If you get an error, please read "Setting Up" and "Options".

3) Now to send this to an Internet server, you must change the first line of the script as noted in "Setting Up".

Also read the FAQ.


Bookmark Menu

Use this menu to set bookmarks in the Perl Editor. You can set up to four bookmarks.

Using the shortcut keys can get you to your editing spots faster. Use Ctrl+1...4 to set a bookmark and Alt+1..4 to go to the corresponding bookmark.


Command Converter

The command converted is used because of the changes that have to be done in the local version of your script (the one used when off-line for testing) and the one you want to publish. Usually changes have to be made that include:

•	Changing the path to the perl interpreter in the first line

•	Some commands that do not work under windows like flock

•	Paths to files that Perl writes that are Unix specific. For example if you want to write a file like "/docs/logs/count.log", in your local version in windows, this must be changed to "count.log" or "\cgi-bin\docs\logs\count.log" if you have created those two directories in c:\apache\cgi-bin.

To fix these problems, you can modify your scripts code to run in two ways, or use the command converter.

First add somewhere this line:

#@Local#?#@Server if you are editing the local version or

#@Server#?#@Local  if you are editing the server version.

This way VPE "knows" what version is run. Load the command converter and add/replace the changes that will occur when you press the "Toggle" button.

An example with the Flock command:

Entered are Local: #flock( and Server: flock(

If VPE finds #@Server#?#@Local and somewhere in your script flock(OUTF,2)

then pressing toggle will:

•	Change the comment to #@Local#?#@Server

•	Change the line to #flock(OUTF,2)

Notice that the remark was swapped at #?. Actually all lines are swapped in this manner in your script when the "toggle" is pressed. For lines like

$Counter='/docs/logs/count.log';#?$Counter='count.log';

flock(CNT,2);#?#flock(CNT,2);

#?print "Local Version";

Will be swapped at #? resulting in

$Counter='count.log';#?$Counter='/docs/logs/count.log';

#flock(CNT,2);#?flock(CNT,2);

  -This would be unaffected from the #flock( in the table

print "Local Version";#?

So you have the option of creating general changes in the table, or adding script-specific changes in your script.

If you do not add the #@Server#?#@Local line, then the command converted will still work, but no toggle button will exist, and no #? comments will be swapped. You will have to do this manually, with the radio box shown.

Included is counter.cgi, that demonstrates writing two versions of a script. Copy first to c:\apache\cgi-bin. Check, the source code as modified so when you press the toggle button, three changes occur, two from the table and one with the use of the #? comments.


Custom Commands
Run Perl with custom parameters

Here you may run Perl with the command line parameters you want.

Use "%File"  to show the current filename (case sensitive).


Edit Menu

The first five items of the Edit menu are the standard you can find in any editor, with their common shortcuts. From these commands, often "Paste" is used to move code from the Template or HTML editor.

•	Make Editor Big: This will maximize the Perl editor.

•	Make Web Page Big: This will maximize the Web Browser

•	URL Encoding: With this command a modeless dialog is brought up, where you can URL encode or decode text. The resulting text can be copied to the clipboard or inserted at the current cursor position in the editor.

•	Code Templates: Brings up the Perl Code Templates

•	Super Quick HTML: Brings up the HTML Code previewer and editor with templates

·	·


F.A.Q.

General Questions

Q: Is Visual Perl Editor a language for making forms on web pages?

A: Visual Perl Editor is not a language. It is a tool that helps programming in Perl. Perl is a language that makes programs for computers. It just happens that it is also good for making cgi scripts, those used for web pages. Actually almost everytime there is some kind of interaction between you and the browser, a perl script is being used, from input boxes to search engines..

Q: Can Visual Perl Editor help me learn Perl?

A: It can help you, especially if you want to deepen in CGI programming, because you can do that offline in windows. However you will not be able to magically do stuff, you must still learn Perl. A good book for an introduction to Perl and CGI programming is: Clinton Pierce, "Teach yourself Perl in 24 hours", Sams publishing.

Q: Why isn't it easy to make windows run CGI scripts?

A: Windows, especially 98 was not made to do this. For script to run from the webbrowser offline, a small server must be loaded when we want to in windows, that actually only server itself, the user of the same computer, and this is an extremely scaled down function of Apache. Also perl languge must be installed, from ActivePerl's package. The steps on how to setup all this are included in Visual Perl Editor's help, and should be followed exactly.

Q: The script can run in a dos-box, but an error is shown if run in the browser.

A: CGi scripts must follow some rules to run, it is not a problem of Visual Perl Editor. We suggest getting a good book about CGI. Another problem might be some commands that in an offline version of the script in windows, do not make sense. Read more in the command converter.

Q: Is Visual Perl Editor compatible with Windows 2000 and NT?

A: Yes it is.

Setting Up

Q: To run Visual Perl Editor I need Apache and Active Perl. Where is the exact URL to download them?

A: Download the latest version of Apache for Win32, at http://www.apache.org/dist/binaries/win32/. The latest version of ActivePerl for Windows is at: http://www.activestate.com/ActivePerl/download.htm (intel build).

Q: What settings should I select in Apache's setup? In ActivePerl?

A: Select installation folder as C:\Apache and minimal installation (just to save space). In ActivePerl select installation folder of C:\Perl.

Q: How do I load apache?

A: Run in from Visual Perl Editor's Tool menu, or select from the start menu the item "Start Apache". Also you can load it from dos, it's C:\Apache\Apache.exe.

Q: When I load Apache, the window opens and then closes immediatelly, and I don't get a chance to read what it says. What can I do?

A: Apache must be giving an error message. To be able to see it, load to command prompt to go to dos, and enter c:\apache\apache so apache loads. The window will not close, so check what the error message is. Also check the last line of the error log at c:\apache\logs\error.log.

Q: Is Apache loaded if the window opens and then closes immediatelly?

A: No it is not. You must always have a console window loaded, that can be minimized, but not closed if you want to run CGI scripts in Visual Perl Editor. This does not apply if you are using Windows 2000 or NT. In this case check if apache is running as a service.

Q: What is the correct way to close the Apache console window when I've finished using Visual Perl Editor?

A: An almost-correct way that's fine if you are using Apache just for offline work and not as a web server is selecting the window and pressing Ctrl-C.

Q: The error message in Apache's log is "failed to get a socket for port 80".

A: This has to do with the network configuration in windows. Go to Settings/Control Panel/Network, and check what get's loaded there. A good idea is to delete the items there and re-install them, but make sure you know what you are doing.  What must be there for sure is a TCP/IP adaptor in Protocols. This applies for both Windows 98 and 2000/NT

Q: When I load a CGI script in Visual Perl Editor' s internal browser, I see again the code of the script!

A: You have associated the cgi extension. Go to Explorer (not Internet Explorer) and select View/Folder Options/[tab] File types. Now in the "registered file types" window, search carefully for file types cgi and pl. When you find the association, remove it.

Q: When I first load Visual Perl Editor, I get an error message and the program terminates. What's wrong?

A: You probably have an old version of Windows 95 without Internet Explorer 5 or above. Try installing a newer version of Internet Explorer, or installing Windows 98 and above.

Q: When I load Visual Perl Editor, I get a Dr. Watson application error (windows NT)

A: The same applies as above. Windows NT 4 ships with IE 2 and this will not work. You must upgrade to IE 5.

Q: Sometimes the changes in the script I make are not reflected in the web browser. Whats wrong?

A: If you see this happening, then try going to the Control Panel / Internet Options / General tab /  Temporary Internet Files / Settings and select "Every visit to the page"

Some free web hosting services with a CGI  directory

Tripod (http://www.tripod.com/)

My CGI Server (http://www.mycgiserver.com/)

Clan World (http://www.clanworld.org/)

Eosnet Communications (http://www.eosnet.com/)

Freeshells (http://www.freeshells.net/)

Virtual Avenue (http://www.virtualave.net/)

World Zone (http://www.worldzone.net/)


File Menu

Here are the standard commands to Open, Save, Save As, Create a new file. Their use is just like any other program.

However, if you want to preview CGI Scripts in a browser, you must save your files in your cgi-bin directory or in it's subdirectories. Read Setting Up and about the Options Dialog for more information.

From here you can also select the command "Send to FTP Server"

When "Unix line endings" is checked, whenever you save the file, the line endings are encoded for unix systems. Whenever you load a file, Visual Perl Editor recognizes the encoding, and will check this menu item if needed.

Note that when you test your script, all changes are changed in a windows format. So before uploading to a unix server, make sure you press "Save" one last time to make sure it's saved correctly.


How to register

"Great little program, ran my perl script for watching our Mail Queue just fine ... Wish I had this when I was building it"

-Phill Hardstaff

Senior Support Engineer

"Visual Perl Editor cuts production time in half. Programming CGI scripts is fun again"

-Chris Brantley

Web Developer

Visual Perl Editor is not a free program. Some features have been disabled in this demo version you have. Registering the program will enable all features of Visual Perl Editor, and enables editing of unlimited sized scripts. After registering, you will receive an e-mail with the full version, and will also receive all future updates.

We are introducing price differention so you can enjoy this program at low-low price that fits your budget:

•	Individuals for personal use may register Visual Perl Editor for only $29.

•	For commercial use, you may register for only $39 for an unlimited site license.

·	·

Both registered customers will receive free of charge future updates.

You can order with a credit-card worldwide. Read Register.txt for information about other means of payment. Accepted currencies are US Dollars and Euros.

Not convinced that you need it?

Please read the introduction to see how you can use it.

Visual Perl Editor Homepage:

http://http://www.xarka.com/vpe.html

Register for Personal Use:

http://shareit1.element5.com/programs.html?productid=131785

Register for Commercial Use:

http://shareit1.element5.com/programs.html?productid=137221


HTML Editor
The Super Quick HTML Editor

Often you have to enter in you perl script HTML code. This window helps you do this job.

The top part of the window has a HTML editor (not perl) where you can write HTML code. Pressing F9 will preview that code instantly in the web browser to the left.

The bottom part contains HTML Templates to add to the HTML window. You can use the buttons of the navigator to edit your templates, or insert them in the code.

After finishing, you can copy all the resulting code in a HTML block of your perl script. If you want to edit such a block from the script, select it and then open the HTML Editor window.


Interpreter Menu

Important: For most of these commands to execute, you must set up Visual Perl Editor in the Options Dialog.

•	Find Errors: This executes perl with a -cw parameter, to check for errors and warnings. The line numbers shown in the console window are the same with those in the bottom-left corner of the editor.

•	Run in Console: Executes your perl program in a console window

•	Dump Output: Dumps output of a perl program in a scrollable window.

·	·

Note that with these three options, you can test visually edit perl programs that are not CGI. If this is what you need, you don't have to load any web-server software.

•	Run in Browser: This will execute the perl script in the right-panel browser. Read more also about the Query. If you are getting an error, read Setting Up.

•	Edit Query: This will bring up the query editor.

•	Clear History List: This will clear all entries in the drop-down query string list. Note that previous entries are saved when the program is closed.

•	View Log: Views the error and access log (usually of apache). The files that get opened are entered in the Options Dialog.

·	·


Introduction

Visual Perl Editor v2.6

by Xarka Software - Harry Kakoulidis

Program and documents are all copyright (c) 2000 Xarka Software.

Visual Perl Editor will help you create CGI scripts in Perl, offline in Windows. The program has two panels, one to edit the script and another that previews the CGI Script in an internal web browser. You can also test the script for errors or run them normally.

Read Setting Up to setup Windows and the Visual Perl Editor for CGI in Perl running.

Features include:

•	Offline editing of Perl Scripts.

•	Live preview of the scripts in the internal web browser.

•	Code-templates to add to your script.

•	Query editor to easily create Query's to be tested with a GET method.

•	URL encoder/decoder.

•	Command converter to handle non supported perl functions in windows

•	Bookmarks.

•	A super quick HTML editor and previewer, with template support.

•	Quickly send your script to an FTP server.

•	Unix line endings support

•	Printing script

·	·	·	·	·

Visual Perl Editor is not Free! Some features have been disabled in this demo version. However for a small amount of money ($29 US) payable on-line with your credit card, you may download the full featured version.

Why should you buy this program? Well, consider the following:

•	Visual Perl Editor is a great learning tool. You can use it to learn Perl and CGI programming in the comfort of a visual editor, without loss of time and money because of loading from dos perl or being for hours on the internet.

·	·	·	·	·

So if you program for hobby or want to introduce yourself in a pleasant way to CGI programming, Visual Perl Editor is for you.

•	Professionals designing perl programs and cgi scripts can use it. You can save much - much time by quickly testing all the ideas you have and increasing productivity.

·	·	·	·	·

For novice or advanced users, for hobby or professional use, Visual Perl Editor is bundled with all the tools you need to make CGI in Perl Programming easy!

Read More on "How to Register"

Please support the work of the author.


License Agreement

EVALUATION VERSION

This is not free software. You are hereby licensed to use this software for evaluation purposes without charge for a period of 30 days.

REGISTERED VERSION

One registered copy of this software may either be used by a single person who uses the software personally on one or more computers, or installed on a single workstation used non simultaneously by multiple people, but not both.

COPYRIGHT RESTRICTION

Xarka software name and any logo or graphics file that represents our software may not be used in any way to promote products developed with our software.  All parts of Xarka's software and products are copyright protected.

DISCLAIMER

THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  IN NO EVENT WILL THE AUTHOR BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING INCIDENTAL OR CONSEQUENTIAL DAMAGES, ARISING OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. YOU ACKNOWLEDGE THAT YOU HAVE READ THIS LICENSE, UNDERSTAND IT AND AGREE TO BE BOUND BY ITS TERMS.

DISTRIBUTION

This software may be distributed freely in its original unmodified and unregistered form. The distribution has to include all files of its original distribution. Distributors may not charge any money for it.

OTHER RESTRICTIONS

You may not modify, reverse engineer, decompile or disassemble this software in any way, including changing or removing any messages or windows.


Main window

The main window of Visual Perl Editor is constructed of two panels. One to edit a CGI Script and another to preview it as a HTML page.

The editor part has a text edit, so you can input GET queries to the script

The Web Browser part has the standard browser buttons.


Option dialog

This dialog should be run when you first start Visual Perl Editor.

Default Domain and Directory

This is a http address that shows the starting directory where your cgi scripts are.

This is usually "http://127.0.0.1/cgi-bin/"

Note that you must save your scripts in the directory that corresponds to that address on your hard drive. In this case "C:\Apache\cgi-bin\"

You can also use subdirectories like for example:

http://127.0.0.1/cgi-bin/test/

And then save to:

C:\Apache\cgi-bin\test\

Path to Perl Interpreter

This shows your path to perl. If you are running for the first time, please reselect it even if you see the correct path.

Default Path

Select here the default path of the Open and Save dialogs

Template for new files

Here you can select a file that is used when opening new scripts

Access and Error log filename

Enter here the filenames of the logs that apache creates to be viewed with the log viewer.

Integrated Debugging

If checked, brings up a window when checking for errors


Query

This is a string that is sent to the CGI Script with a GET Method. You can edit this string manually, or use the query editor.


Query Editor

The query editor is called when you press the Edit button in the main window.

This brings up two ways to edit the query:

•	Using the query editor you can make up query's like "fname=Harry&email=kcm%40mailbox.gr". The first row is the Name, and the second is the Value. Use this to emulate form components of a web page.

•	You can also edit the string manually to take any other form.


Send to FTP Server

With this dialog you can send your current script to FTP servers. If you want, automatically it can also change the file mode with a CHMOD command.

To use fill it the boxes:

•	Connect To: Select an FTP server. Ex: ftp.tripod.com

•	Port: Select the port, usually 21.

•	Directory: Select the directory for the file to be uploaded. Ex: cgi-bin

•	User, Password: Enter your username and password

•	chmod: Enter the file mode to change after the upload. Usually this is 755, however some servers automatically change the mode of *.cgi files. In this case, leave blank.

Warning: In case a file with the same name already exists, it is replaced without warning.

Also note that most servers are case sensitive. For example "Test.cgi" is different than "test.cgi".

Press "Send" to upload the file. If anything goes wrong, you will get a warning message about it.

Some web hosting services do not offer CGI Script processing. You may want to contant your service to ask at which directory you can send your custom scripts.


Setting up
Setting up Windows to run CGI Scripts in Perl

1) Get Apache Web server for Windows (http://www.apache.org). Select the installation  folder as C:\Apache and if you want to save space, minimal installation.

Download page.

Direct link. (might not work if newer version is available)

2) Get Active Perl intel build (http://www.activestate.com/). The installation folder should be C:\Perl.

Download page.

Direct link. (might not work if newer version is available)

3) Open notepad and Go to the file C:\Apache\conf\httpd.conf. Find the line "ServerName", uncomment it and change to

ServerName 127.0.0.1

(not #ServerName 127.0.0.1)

4) Apache runs by selecting "Start Apache" from the start menu. Start it (a console window - minimize it) and your web browser, and enter http://127.0.0.1 (you don't have to be on the internet). If you get a message "Go offline" press cancel. You should see the Apache's help. If not, try putting any html document named index.html in the directory C:\Apache\htdocs\

Note that whenever CGI Scripts are to be run, apache must be loaded and working. If apache's window opens and closes very fast, it has not been loaded. Check the F.A.Q if this happens.

5) Now you are OK. Whatever CGI script you put in directory C:\Apache\cgi-bin, can be run by putting an address in your browser http://127.0.0.1/cgi-bin/test.cgi etc. A good idea is to try this also. Copy test.cgi into the directory c:\apache\cgi-bin and enter in your browser the above address. If you get errors, something is wrong.

6) IMPORTANT: To run CGI scripts in windows, you must change their first line to

#!C:\Perl\bin\perl.exe  (where you have your perl interpreter)

When you upload them afterwards to the server, change to

#!/usr/local/bin/perl  (or wherever perl is at the server)

You can use the command converter to do this faster.

Now you must do two more things to setup Visual Perl Editor. Please read about the Options Dialog.

Also read about how to send your scripts to an internet server on "Send to FTP Server"


Template Editor

This window contains perl templates to add to your script. Using the buttons of the navigator, you can add/edit your own templates.

Copy will copy the template to the clipboard. Insert will insert it in the current cursor position in the CGI Script.


Tool Menu

This menu lists the tools you have configured. Select "Configure" to bring up a dialog. Here you can add all valid file types so you can quickly launch files within Visual Perl Editor.

Some entrys have been included. They will work if you have configured Apache and Perl in the directories specified in "Setting Up".

You can also add these strings in the "parameter" section (case sensitive).

•	%File - Enters the current filename

•	%Query - Promts for a user entry. A good example for the use of this is:

•	%Word - Return the word under the cursor

perldoc -tf %Query

If you add in the parameters "-tf %Query", this will promt for a word.


URL Encoder

With this dialog you can URL Encode and Decode strings, if you need them in your script.


Web Browser Menu

This menu contains the standard browse buttons. Very useful is the Reload button, when testing your scripts, and also the Open URL.

You may use the last for addressed like "http://127.0.0.1/test.html", if you have also created a web page that calls the CGI Script.

In most cases the CGI is called from a web page as "http://127.0.0.1/cgi-bin/test.cgi"